home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / u_man / cat1 / mkf2c.z / mkf2c
Encoding:
Text File  |  2002-10-03  |  14.4 KB  |  291 lines
  1. MKF2C(1)                                             Last changed: 12-23-98
  2.  
  3.  
  4. NNAAMMEE
  5.      mmkkff22cc - Generate FORTRAN-C interface routines
  6.  
  7. SSYYNNOOPPSSIISS
  8.      mmkkff22cc [ _o_p_t_i_o_n_s ] [ ccpprroogg..ffcc [ ccpprroogg..ss ] ]
  9.  
  10. IIMMPPLLEEMMEENNTTAATTIIOONN
  11.      IRIX systems
  12.  
  13. DDEESSCCRRIIPPTTIIOONN
  14.      mmkkff22cc is used to generate assembly-language routines to provide
  15.      greater flexibility when calling a C function from a FORTRAN routine.
  16.  
  17.      mmkkff22cc accepts as input a set of C functions, and produces an
  18.      assembly-language interface routine in the output file.  If the input
  19.      and output files are not specified, mmkkff22cc reads from stdin and writes
  20.      to stdout.  The input may be a copy of the actual C file being
  21.      interfaced, perhaps filtered by the program eexxttcceennttrryy(1).  The output
  22.      of mmkkff22cc is an assembly-language (..ss) file that must be assembled with
  23.      aass(1), and loaded with the FORTRAN and C routines that are to be
  24.      interfaced.
  25.  
  26.      The assembly-language output is KPIC code which must be assembled with
  27.      the --KKPPIICC option to aass(1) unless an unshared .o is desired.
  28.  
  29.      mmkkff22cc uses the parameter declarations in the C function headers to
  30.      transform each parameter of the calling language to that of the
  31.      receiving language.  The standard basic C types attached to the
  32.      parameters are used to determine the object each parameter represents
  33.      - i.e., whether it is a value or pointer, its size, whether it is
  34.      unsigned, etc.
  35.  
  36.      For C functions in K&R style, the opening and closing brace of the
  37.      function body must be present.  Information in the body of the
  38.      function is ignored.  For C functions in ANSI C function prototype
  39.      style, the function may be either a definition (and whatever is
  40.      between the opening and closing brace is ignored) or a declaration
  41.      (ie, with ; rather than {}).  Function parameters in ANSI C style
  42.      function prototypes need not name the parameters.  Function parameters
  43.      in ANSI C style function prototypes cannot use typedef names to
  44.      declare parameter types.
  45.  
  46.      mmkkff22cc expects its input to consist solely of the functions it is to
  47.      interface, comments, and lines which begin with the preprocessor
  48.      control character '#'.  It can match braces, enabling it to bound
  49.      function bodies.  It cannot, however, understand other C constructs
  50.      normally occurring at the global level (typedefs, structure
  51.      declarations, data declarations, function prototypes, etc.).  Such
  52.      unrecognized constructs must be eliminated from the input (this is the
  53.      purpose of eexxttcceennttrryy(1)).
  54.  
  55.      mmkkff22cc will ignore functions of storage class ssttaattiicc.
  56.  
  57.      The simplest way to generate an interface for a C function is to
  58.      hand-code a copy of the function which consists of the entry and
  59.      parameter declarations with an empty body.  This stub, which is
  60.      traditionally suffixed with ..ffcc is then used as input to mmkkff22cc, and
  61.      the resultant ..ss file is assembled and linked into the executable.
  62.      The root name of the stub file must differ from the root name of the
  63.      file containing the actual C functions (so that the name of the
  64.      resultant ..oos differ).  NOTE: The -KPIC switch must be given to aass(1)
  65.      unless the object is to be non-shared.
  66.  
  67.           mkf2c foo.fc foo.s
  68.           as -KPIC foo.s -o foo.o
  69.  
  70.      It is also possible to create wrappers from existing C source code.
  71.      This is done by adding special rules to your makefile and adding
  72.      special comments around each function for which an interface is to be
  73.      generated.  See the example at the end of this man page.
  74.  
  75.      The following are options to mmkkff22cc(1):
  76.  
  77.      --3322       Generate wrappers with (old) 32-bit calling conventions.  At
  78.                this time, it is the default, but may change as different
  79.                ABIs become the future default.
  80.  
  81.      --6644       Generate wrappers with 64-bit pointer sizes, and using the
  82.                64 bit calling conventions.
  83.  
  84.      --nn3322      Generate wrappers with the n32 calling conventions.
  85.  
  86.      --ff        Suppress extending floats to doubles across the call.
  87.                Normally, formal parameters of type ffllooaatt in the (K&R) C
  88.                input to mmkkff22cc are dereferenced and converted to type ddoouubbllee
  89.                across the interface, to conform to C calling conventions.
  90.                This option suppresses the conversion to ddoouubbllee.  If this
  91.                option is selected, the receiving routine in C should have a
  92.                pprroottoottyyppee with the ffllooaatt parameters declared correctly.  For
  93.                declarations input to mmkkff22cc in ANSI C style function
  94.                prototypes float arguments are not extended, so --ff need not
  95.                be supplied.
  96.  
  97.      --oooouuttppuutt  Name the output file oouuttppuutt.  If the output filename is not
  98.                specified by a --oo ffiilleennaammee switch, mmkkff22cc will use the second
  99.                filename appearing in its argument list as the output file
  100.                name.  This method must be used to generate an interface
  101.                routine in a file when the input is from ssttddiinn.
  102.  
  103.      --UU        Normally, upper case characters appearing in FORTRAN
  104.                external names are mapped to lower case.  This option
  105.                suppresses that mapping, allowing FORTRAN external names to
  106.                be of mixed case.  This option should be used in conjunction
  107.                with the --UU option to ff7777(1).
  108.  
  109.      --ssiiggnneedd,,--uunnssiiggnneedd
  110.                Specify the ssiiggnneedd attribute of single-character parameters.
  111.                The setting of this option determines whether a scalar
  112.                parameter of type cchhaarr (in the C input to mmkkff22cc), which
  113.                corresponds to a FORTRAN argument of type cchhaarraacctteerr**11,
  114.                should be sign-extended across the interface.  The default
  115.                setting is uunnssiiggnneedd.
  116.  
  117.      --uu        Keep underscores in function names.  By default underscores
  118.                are removed and a warning is issued.
  119.  
  120.      --ll        By default, mmkkff22cc truncates FORTRAN external names to ssiixx
  121.                characters to conform to the ANSI standard and to be
  122.                backwards-compatible with the IRIS 4D Series.  This switch
  123.                allows the maximum number of characters in FORTRAN external
  124.                names to be the same as that enforced by the FORTRAN front-
  125.                end (currently 32).  If this switch is not specified, the
  126.                FORTRAN program should have the C function name truncated to
  127.                six characters at the call.
  128.  
  129.      --ww        Inhibit the generation of warning messages.  Because
  130.                creating wrappers can cause confusion, mmkkff22cc issues warning
  131.                messages for constructs that will result in an interface
  132.                that is not normal for C (i.e., the C side of the interface
  133.                must take special precautions when accessing the parameters
  134.                or naming the routines).  An example of this would be
  135.                passing a FORTRAN character variable as a C character array.
  136.                mmkkff22cc knows that this situation requires C to use special
  137.                care when manipulating the string, as it is not null-
  138.                terminated, and, hence, it generates a warning message.  It
  139.                is recommended that --ww only be used by programmers
  140.                experienced with the generation of wrappers.
  141.  
  142.      --ccaallll__ssaammee__ddssoo
  143.                This is used when the wrapper and the target C function will
  144.                be placed in the same DSO.  A further optimization is taken
  145.                which removes the restoring of the gp register after the
  146.                call return.
  147.  
  148. EEXXAAMMPPLLEESS
  149.      In the following example, a FORTRAN program wants to call a C function
  150.      AAllllPPaarraammeetteerrss with many parameters.  The FORTRAN program is in the
  151.      file ff..ff and the C function is in the file cc..cc.  These are the only
  152.      two files in the program.  The special comments /*CENTRY*/ and
  153.      /*ENDCENTRY*/ have been added to the C source code to bracket the
  154.      function for which an interface is to be generated.  The following is
  155.      the C function header:
  156.  
  157.    /* CENTRY */
  158.    AllParameters(i,s,c,cptr,ptr1,ptr2,ar1,f,d,d1,struct1,string1,string2,u)
  159.    short s;
  160.    char c,*cptr;
  161.    int *ptr1;
  162.    char *ptr2[];
  163.    short ar1[];
  164.    float f;
  165.    double d,*d1;
  166.    struct test_s *struct1;
  167.    char string1[],string2[30];
  168.    sometype u;
  169.    {
  170.         /*
  171.         The C function body is ignored by mkf2c.
  172.         */
  173.    }
  174.    /* ENDCENTRY */
  175.  
  176.      When this function is run through mmkkff22cc, a complaint will be issued
  177.      about not understanding the type of parameter uu.  It will be assumed
  178.      to be a simple pointer.  Additionally, a warning about passing the
  179.      parameters, ssttrriinngg11 and ssttrriinngg22, as simple pointers will be issued.
  180.      (These FORTRAN character variables each have an associated length that
  181.      is passed as a hhiiddddeenn parameter to the C function, at the end of the
  182.      parameter list.  These additional parameters may be accessed by the C
  183.      function by the use of the vvaarraarrggss macros.  See the FFOORRTTRRAANN LLaanngguuaaggee
  184.      RReeffeerreennccee MMaannuuaall for more information.)
  185.  
  186.      The ii parameter will be assumed to be of type iinntt, as it is by the C
  187.      compiler ccccoomm during compilation.
  188.  
  189.      Several items are noteworthy about the parameters in this example.
  190.      The parameters ii, ss, cc, ff, and dd will be dereferenced across the call.
  191.      The parameter ff will be extended to a ddoouubbllee across the call unless
  192.      the --ff switch is given to mmkkff22cc(1).  The parameters ppttrr11, ppttrr22, aarr11,
  193.      dd11, ssttrruucctt11, ssttrriinngg11, and ssttrriinngg22 will be passed as simple pointers.
  194.      The FORTRAN cchhaarraacctteerr**11 variable which is passed as cc will be
  195.      dereferenced and extended to a lloonngg across the call.  If the --ssiiggnneedd
  196.      switch is specified, cc will be sign-extended when being dereferenced.
  197.      A copy of parameter ccppttrr will be made and the copy null-terminated.  A
  198.      pointer to this copy will be passed.  The C entry point will be named
  199.      AAllllPPaarraammeetteerrss.  The FORTRAN entry point name depends on whether or not
  200.      the --UU and/or the --ll switches have been given.  The various
  201.      combinations of these switches and their effect is detailed below:
  202.  
  203.      Switches
  204.           FORTRAN Entry
  205.  
  206.      <<nnoonnee>>
  207.           aallllppaarr__
  208.  
  209.      --ll   aallllppaarraammeetteerrss__
  210.  
  211.      --UU   AAllllPPaarr__
  212.  
  213.      --ll --UU
  214.           AAllllPPaarraammeetteerrss__
  215.  
  216.      The program can be made easily and the interface generated
  217.      automatically by adding the following special rules to your makefile:
  218.  
  219.       # .fc must be added to your SUFFIXES between .c and .o
  220.       .SUFFIXES:
  221.       .SUFFIXES: .o .fc .c .s .f
  222.  
  223.       F2CFLAGS=
  224.       ASFLAGS=-KPIC
  225.  
  226.       test:  f.o c.o
  227.              f77 -o test f.o c.o
  228.  
  229.       # note -- each .c file containing routines to be interfaced must have
  230.       # a dependency such as the following
  231.       c.o: c.fc
  232.  
  233.       .fc.o:
  234.               cc $(CFLAGS) -c $*.c
  235.               mkf2c $(F2CFLAGS) $< $*.s
  236.               as $(ASFLAGS) -o $*.wo $*.s
  237.               ld -r $*.o $*.wo -o $*.tmp
  238.               mv $*.tmp $*.o
  239.               rm -f $*.s $*.wo
  240.  
  241.       .c.fc:
  242.               extcentry $*.c $*.fc
  243.  
  244.  
  245.       clean:
  246.            rm -f *.o test *.fc
  247.  
  248.      In the make, the program eexxttcceennttrryy will be run on cc..cc to produce cc..ffcc.
  249.      This program (see eexxttcceennttrryy(1)) will copy to cc..ffcc all text in cc..cc
  250.      which is between the special comments ** CCEENNTTRRYY ** and ** EENNDDCCEENNTTRRYY **.
  251.      mmkkff22cc will then be run on cc..ffcc, and the make variable FF22CCFFLLAAGGSS will be
  252.      passed to it.  The C source will be compiled with cccc(1) (using cccc
  253.      $$CCFFLLAAGGSS), and the output of mmkkff22cc will be assembled (with aass
  254.      $$AASSFFLLAAGGSS).  These two ..oos will then be loaded together into a single
  255.      relocatable named cc..oo.
  256.  
  257.      If it is desired to pass mmkkff22cc(1) some flags (e.g., --ll and --ssiiggnneedd),
  258.      the mmaakkee variable FF22CCFFLLAAGGSS should be set in the makefile, as
  259.  
  260.           F2CFLAGS = -signed -l
  261.  
  262. DDIIAAGGNNOOSSTTIICCSS
  263.      mmkkff22cc can detect such things as a formal parameter having its type
  264.      declared when it is not in the formal parameter list.  A few such
  265.      cases give intelligible error messages.  The program will issue
  266.      warnings about types it does not understand.  The default type
  267.      assigned in such cases is ssiimmppllee ppooiinntteerr.  mmkkff22cc will also delete
  268.      characters from FORTRAN entry names that are illegal (such as
  269.      underscores) and issue a warning message.  Most errors that the
  270.      programs detect are indicated only by the source line number.
  271.  
  272.      If mmkkff22cc encounters an error that it cannot remedy, it will abort,
  273.      giving the line number on which the error occurred.  The resultant ..ss
  274.      file will be removed, and an error exit will be taken.
  275.  
  276.      Because of its limited error diagnostic ability, it is advisable to
  277.      use cccc(1) to determine whether the input syntax is correct before
  278.      passing it to mmkkff22cc..
  279.  
  280. BBUUGGSS
  281.      mmkkff22cc does not understand the ANSI notation aa((vvooiidd)) as meaning a
  282.      function with no arguments.
  283.  
  284.      In ANSI C style function prototypes, ttyyppeeddeeff names cannot be used.
  285.  
  286. SSEEEE AALLSSOO
  287.      eexxttcceennttrryy(1), cccc(1), FORTRAN Language Reference Manual
  288.  
  289.      This man page is available only online.
  290.  
  291.